Node effect renderer class. More...

#include <kanzi/core.ui/node/node_effect_renderer2d.hpp>

Inheritance diagram for kanzi::NodeEffectRenderer2D:

Classes
struct	EffectPass
	Effect pass configuration. More...

struct	EffectRenderState
	Render state configuration to use with an effect pass. More...

Public Member Functions
void	applyEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements, TextureSharedPtr sourceContent)
	Applies the effect on the source content provided as texture.

void	beginEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements)
	Begins the effect.

void	blitEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
	Blits the effect to the current framebuffer.

void	endEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)
	Ends the effect.

NodeEffect2DSharedPtr	getEffect () const
	Get NodeEffect2D instance where this renderer has been instantiated from.

size_t	getEffectPassCount () const
	Gets the number of effect passes.

bool	isLayeredOnTop () const
	Whether a compatible effect renders logically on top of its source content.

bool	isRenderEffectOnlyEnabled () const
	Whether the effect only mode is enabled.

void	restoreResources ()
	Restores resources after the rendering context has been lost.

void	setRenderEffectOnly (bool renderEffectOnly)
	Sets the render effect only mode.

virtual bool	supportsBlitBlendMode (int blendMode)
	Whether the effect is compatible with a given blend mode.

virtual	~NodeEffectRenderer2D ()
	Declare NodeEffectRenderer2D as not movable nor copyable.

Protected Types
using	EffectPassContainer
	Container for effect passes.

Protected Member Functions
EffectPass &	addEffectPass ()
	Adds an effect pass and gets a reference to that pass.

virtual void	beginEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements)=0
	Begin effect.

void	beginInitialEffectPass (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const CompositionContentRequirements &requirements)
	Begins the initial effect pass (effect pass at index 0).

virtual void	blitEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)=0
	Blit effect to current framebuffer.

void	blitEffectPass (int effectPassIndex, Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
	Blits the effect pass and handles the perspective transform if necessary.

void	blitFinalEffectPass (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
	Blits the final effect pass, whose index is getEffectPassCount() - 1, and handles the perspective transform if necessary.

void	blitIntermediateEffectPass (int effectPassIndex, Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)
	Blits the intermediate effect pass.

void	clearRenderTarget (Renderer3D &renderer, CompositionStack &compositionStack, NativeFramebufferHandle framebufferHandle, ColorRGBA clearColor)
	Clears the native framebuffer with a given color.

void	clearRenderTarget (Renderer3D &renderer, CompositionStack &compositionStack, TextureSharedPtr texture, ColorRGBA clearColor)
	Clears the render target texture with a given color.

void	configureInitialEffectPass (Vector2 sourceContentSize)
	Configures the initial effect pass.

virtual void	endEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)=0
	End effect.

void	endInitialEffectPass (CompositionStack &compositionStack)
	Ends the initial effect pass, whose index is 0.

void	finalizeEffectPasses ()
	Finalizes the effect passes.

Vector2	getEffectInputTexelSize (int effectPassIndex, int inputIndex)
	Gets the texel size of the input effect pass texture in texture coordinates.

EffectPass &	getEffectPass (int index)
	Gets a reference to the effect pass at a given index.

int	getLastEffectPassIndex () const
	Gets the index of the last effect pass.

bool	isInitialPassRenderTargetTemporary () const
	Whether the initial pass render target is temporary.

	NodeEffectRenderer2D (NodeEffect2DSharedPtr nodeEffect)
	Constructor.

virtual void	onRenderEffectOnlyChanged ()
	Kanzi calls this when the render effect only mode changes.

void	releaseEffectPassInputRenderTargets (EffectPass &currentEffectPass, CompositionManager *compositionManager)
	Releases those temporary render targets used by input that have EffectPass::Input::releaseRenderTarget set to true.

void	removeAllEffectPasses ()
	Removes all user-added effect passes, but leaves the internal initial effect pass.

virtual void	restoreResourcesOverride ()=0
	Restore resource after rendering context has been lost.

void	setLayeredOnTop (bool layeredOnTop)
	Sets whether the effect is layered on top of the source content.

Static Protected Attributes
static constexpr int	InitialEffectPassIndex
	Effect pass index for the initial pass.

Detailed Description

Node effect renderer class.

See also: NodeEffect2D, NodeEffectPrefab2D, NodeEffectTemplate2D

Since: Kanzi 3.9.0

Member Typedef Documentation

◆ EffectPassContainer

using kanzi::NodeEffectRenderer2D::EffectPassContainer

protected

Container for effect passes.

Constructor & Destructor Documentation

◆ ~NodeEffectRenderer2D()

virtual kanzi::NodeEffectRenderer2D::~NodeEffectRenderer2D ( )

virtual

Declare NodeEffectRenderer2D as not movable nor copyable.

Destructor.

◆ NodeEffectRenderer2D()

kanzi::NodeEffectRenderer2D::NodeEffectRenderer2D ( NodeEffect2DSharedPtr nodeEffect )

explicitprotected

Constructor.

Parameters

nodeEffect NodeEffect2D instance associated with this renderer.

Member Function Documentation

◆ getEffect()

NodeEffect2DSharedPtr kanzi::NodeEffectRenderer2D::getEffect ( ) const

Get NodeEffect2D instance where this renderer has been instantiated from.

◆ beginEffect()

void kanzi::NodeEffectRenderer2D::beginEffect	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const Matrix3x3 &	worldTransform,
		const CompositionContentRequirements &	requirements )

Begins the effect.

Call this function before rendering the source content for the effect.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
worldTransform	2D affine world transform used by the node.
requirements	Requirements for the effect contents.

Since: Kanzi 3.9.7 bundle requirements to struct.

◆ endEffect()

void kanzi::NodeEffectRenderer2D::endEffect	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager )

Ends the effect.

Call this function after rendering the source content for the effect.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.

◆ applyEffect()

void kanzi::NodeEffectRenderer2D::applyEffect	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const Matrix3x3 &	worldTransform,
		const CompositionContentRequirements &	requirements,
		TextureSharedPtr	sourceContent )

Applies the effect on the source content provided as texture.

This is an alternative to beginEffect() and endEffect(). Call either applyEffect() or beginEffect() followed by endEffect(). Do not mix them during the application of an effect.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
worldTransform	2D affine world transform used by the node.
requirements	Requirements for the effect contents.
sourceContent	Source content as a texture. You can use this in place of the initial effect pass. The texture must include a one-pixel wide transparent black padding around the content.

Since: Kanzi 3.9.8.

◆ blitEffect()

void kanzi::NodeEffectRenderer2D::blitEffect	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const QuadDescription &	effectQuad,
		const Matrix3x3 &	transform,
		const Matrix4x4 *	perspectiveMatrix,
		const Matrix4x4 *	projectionMatrix,
		int	blendMode,
		bool	needsClear )

Blits the effect to the current framebuffer.

Call this function after NodeEffectRenderer2D::endEffect when you want to blit the effect to screen. You can use this function to implement perspective projection, if you provide the relevant matrices.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
effectQuad	Potentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform	2D affine transform to use for rendering the effect quad.
perspectiveMatrix	Optional perspective matrix to use.
projectionMatrix	Optional projection matrix to use when rendering with perspective transform.
blendMode	The blend mode to use for the effect blit.
needsClear	Whether the current render target needs to be cleared before rendering.

Since: Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.

◆ restoreResources()

void kanzi::NodeEffectRenderer2D::restoreResources ( )

Restores resources after the rendering context has been lost.

◆ getEffectPassCount()

size_t kanzi::NodeEffectRenderer2D::getEffectPassCount ( ) const

Gets the number of effect passes.

Returns: The number of effect passes.

◆ setRenderEffectOnly()

void kanzi::NodeEffectRenderer2D::setRenderEffectOnly ( bool renderEffectOnly )

Sets the render effect only mode.

When enabled, compatible effects render only the effect without the source content.

Parameters

renderEffectOnly Whether to render only the effect. Default is false.

Since: Kanzi 3.9.8.

◆ isRenderEffectOnlyEnabled()

bool kanzi::NodeEffectRenderer2D::isRenderEffectOnlyEnabled ( ) const

Whether the effect only mode is enabled.

Returns: If effect only mode is enabled, true, otherwise false.

Since: Kanzi 3.9.8.

◆ isLayeredOnTop()

bool kanzi::NodeEffectRenderer2D::isLayeredOnTop ( ) const

Whether a compatible effect renders logically on top of its source content.

Returns: If effect is rendered on top of its source content, true, otherwise false.

Since: Kanzi 3.9.8.

◆ supportsBlitBlendMode()

virtual bool kanzi::NodeEffectRenderer2D::supportsBlitBlendMode ( int blendMode )

virtual

Whether the effect is compatible with a given blend mode.

See blitEffect(). If an effect is not compatible with a blend mode, you must composite that effect and use the blend mode when blitting the composite. All effects are compatible with the GraphicsBlendModePremultipliedAlpha blend mode.

Parameters

blendMode The blend mode to test.

Returns: If the effect is compatible with the blend mode, true, otherwise false.

Since: Kanzi 3.9.8.

Reimplemented in kanzi::OutlineEffectRenderer2D, and kanzi::ShadowEffectRenderer2D.

◆ beginEffectOverride()

virtual void kanzi::NodeEffectRenderer2D::beginEffectOverride	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const Matrix3x3 &	worldTransform,
		const CompositionContentRequirements &	requirements )

protectedpure virtual

Begin effect.

Should be called before the source content for the effect is rendered.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
worldTransform	2D affine world transform used by the node.
requirements	Requirements for the effect contents.

Since: Kanzi 3.9.7 bundle requirements to struct.

Implemented in kanzi::OutlineEffectRenderer2D.

◆ endEffectOverride()

virtual void kanzi::NodeEffectRenderer2D::endEffectOverride	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager )

protectedpure virtual

End effect.

Should be called after the source content for the effect has been rendered.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.

Implemented in kanzi::OutlineEffectRenderer2D.

◆ blitEffectOverride()

virtual void kanzi::NodeEffectRenderer2D::blitEffectOverride	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const QuadDescription &	effectQuad,
		const Matrix3x3 &	transform,
		const Matrix4x4 *	perspectiveMatrix,
		const Matrix4x4 *	projectionMatrix,
		int	blendMode,
		bool	needsClear )

protectedpure virtual

Blit effect to current framebuffer.

Should after NodeEffectRenderer2D::endEffect when the effect should be blitted to screen. Can be used to implement perspective projection if relevant matrices are provided.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
effectQuad	Potentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform	2D affine transform to use for rendering the effect quad.
perspectiveMatrix	Optional perspective matrix to use.
projectionMatrix	Optional projection matrix to use when rendering with perspective transform.
blendMode	The blend mode to use for the effect blit.
needsClear	Whether the current render target needs to be cleared before rendering.

Since: Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.

Implemented in kanzi::OutlineEffectRenderer2D.

◆ restoreResourcesOverride()

virtual void kanzi::NodeEffectRenderer2D::restoreResourcesOverride ( )

protectedpure virtual

Restore resource after rendering context has been lost.

Implemented in kanzi::OutlineEffectRenderer2D.

◆ onRenderEffectOnlyChanged()

virtual void kanzi::NodeEffectRenderer2D::onRenderEffectOnlyChanged ( )

protectedvirtual

Kanzi calls this when the render effect only mode changes.

Reimplemented in kanzi::OutlineEffectRenderer2D.

◆ clearRenderTarget() [1/2]

void kanzi::NodeEffectRenderer2D::clearRenderTarget	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		TextureSharedPtr	texture,
		ColorRGBA	clearColor )

protected

Clears the render target texture with a given color.

Parameters

renderer	Renderer3D to use.
compositionStack	CompositionStack to use.
texture	Render target texture to clear.
clearColor	Color to use for the clear.

◆ clearRenderTarget() [2/2]

void kanzi::NodeEffectRenderer2D::clearRenderTarget	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		NativeFramebufferHandle	framebufferHandle,
		ColorRGBA	clearColor )

protected

Clears the native framebuffer with a given color.

Parameters

renderer	Renderer3D to use.
compositionStack	CompositionStack to use.
framebufferHandle	Framebuffer handle to use.
clearColor	Color to use for the clear.

◆ addEffectPass()

EffectPass & kanzi::NodeEffectRenderer2D::addEffectPass ( )

protected

Adds an effect pass and gets a reference to that pass.

Adding an effect pass invalidates references to previously added effect passes. You must add at least two effect passes. The first pass renders the contents into a render target texture, and the last pass blits the effect result.

Returns: EffectPass reference to the just added effect pass.

◆ getLastEffectPassIndex()

int kanzi::NodeEffectRenderer2D::getLastEffectPassIndex ( ) const

protected

Gets the index of the last effect pass.

Returns: The index of the last effect pass or InitialEffectPassIndex if there are no effect passes added by user.

◆ getEffectPass()

EffectPass & kanzi::NodeEffectRenderer2D::getEffectPass ( int index )

protected

Gets a reference to the effect pass at a given index.

Parameters

index Index of the effect pass.

Returns: Reference to EffectPass instance at the given index.

◆ removeAllEffectPasses()

void kanzi::NodeEffectRenderer2D::removeAllEffectPasses ( )

protected

Removes all user-added effect passes, but leaves the internal initial effect pass.

◆ finalizeEffectPasses()

void kanzi::NodeEffectRenderer2D::finalizeEffectPasses ( )

protected

Finalizes the effect passes.

Call this function after you have added and configured all effect passes. This function sets EffectPass::Input::releaseRenderTarget and in debug build checks whether all render pass outputs are in use.

◆ beginInitialEffectPass()

void kanzi::NodeEffectRenderer2D::beginInitialEffectPass	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const CompositionContentRequirements &	requirements )

protected

Begins the initial effect pass (effect pass at index 0).

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
requirements	Requirements for the effect contents.

Since: Kanzi 3.9.7 bundle requirements to struct.

◆ endInitialEffectPass()

void kanzi::NodeEffectRenderer2D::endInitialEffectPass ( CompositionStack & compositionStack )

protected

Ends the initial effect pass, whose index is 0.

Parameters

compositionStack CompositionStack to use.

◆ blitIntermediateEffectPass()

void kanzi::NodeEffectRenderer2D::blitIntermediateEffectPass	(	int	effectPassIndex,
		Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager )

protected

Blits the intermediate effect pass.

If intermediate effect passes exist, blit them in order starting from index 1 to getEffectPassCount() - 2.

Parameters

effectPassIndex	Index of the effect pass to use.
renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.

◆ blitFinalEffectPass()

void kanzi::NodeEffectRenderer2D::blitFinalEffectPass	(	Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const QuadDescription &	effectQuad,
		const Matrix3x3 &	transform,
		const Matrix4x4 *	perspectiveMatrix,
		const Matrix4x4 *	projectionMatrix,
		int	blendMode,
		bool	needsClear )

protected

Blits the final effect pass, whose index is getEffectPassCount() - 1, and handles the perspective transform if necessary.

Parameters

renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
effectQuad	Potentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform	2D affine transform to use for rendering the effect quad.
perspectiveMatrix	Optional perspective matrix to use.
projectionMatrix	Optional projection matrix to use when rendering with perspective transform.
blendMode	The blend mode to use for the effect blit.
needsClear	Whether the current render target needs to be cleared before rendering.

Since: Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.

◆ blitEffectPass()

void kanzi::NodeEffectRenderer2D::blitEffectPass	(	int	effectPassIndex,
		Renderer3D &	renderer,
		CompositionStack &	compositionStack,
		CompositionManager *	compositionManager,
		const QuadDescription &	effectQuad,
		const Matrix3x3 &	transform,
		const Matrix4x4 *	perspectiveMatrix,
		const Matrix4x4 *	projectionMatrix,
		int	blendMode,
		bool	needsClear )

protected

Blits the effect pass and handles the perspective transform if necessary.

Parameters

effectPassIndex	Index of the effect pass to use.
renderer	Renderer to use.
compositionStack	CompositionStack to use.
compositionManager	CompositionManager to use.
effectQuad	Potentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform	2D affine transform to use for rendering the effect quad.
perspectiveMatrix	Optional perspective matrix to use.
projectionMatrix	Optional projection matrix to use when rendering with perspective transform.
blendMode	The blend mode to use for the effect blit.
needsClear	Whether the current render target needs to be cleared before rendering.

Since: Kanzi 3.9.8

◆ getEffectInputTexelSize()

Vector2 kanzi::NodeEffectRenderer2D::getEffectInputTexelSize	(	int	effectPassIndex,
		int	inputIndex )

protected

Gets the texel size of the input effect pass texture in texture coordinates.

You can call this function only after the source effect pass has obtained a valid render target.

Parameters

effectPassIndex	Effect pass index.
inputIndex	Input index.

Returns: Size of texel in texture coordinates.

◆ releaseEffectPassInputRenderTargets()

void kanzi::NodeEffectRenderer2D::releaseEffectPassInputRenderTargets	(	EffectPass &	currentEffectPass,
		CompositionManager *	compositionManager )

protected

Releases those temporary render targets used by input that have EffectPass::Input::releaseRenderTarget set to true.

Parameters

currentEffectPass	Reference to the effect pass whose referenced render targets to release if necessary.
compositionManager	CompositionManager used to get the temporary render targets.

◆ isInitialPassRenderTargetTemporary()

bool kanzi::NodeEffectRenderer2D::isInitialPassRenderTargetTemporary ( ) const

protected

Whether the initial pass render target is temporary.

See applyEffect().

Returns: If the initial pass used a temporary render target, true, otherwise false.

Since: Kanzi 3.9.8

◆ configureInitialEffectPass()

void kanzi::NodeEffectRenderer2D::configureInitialEffectPass ( Vector2 sourceContentSize )

protected

Configures the initial effect pass.

Parameters

sourceContentSize Size of the source content.

Since: Kanzi 3.9.8

◆ setLayeredOnTop()

void kanzi::NodeEffectRenderer2D::setLayeredOnTop ( bool layeredOnTop )

protected

Sets whether the effect is layered on top of the source content.

Parameters

layeredOnTop If layered on top of the source content, true, otherwise false.

Since: Kanzi 3.9.8

Member Data Documentation

◆ InitialEffectPassIndex

constexpr int kanzi::NodeEffectRenderer2D::InitialEffectPassIndex

staticconstexprprotected

Effect pass index for the initial pass.

The documentation for this class was generated from the following file:

kanzi/core.ui/node/node_effect_renderer2d.hpp

Classes

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ EffectPassContainer

Constructor & Destructor Documentation

◆ ~NodeEffectRenderer2D()

◆ NodeEffectRenderer2D()

Member Function Documentation

◆ getEffect()

◆ beginEffect()

◆ endEffect()

◆ applyEffect()

◆ blitEffect()

◆ restoreResources()

◆ getEffectPassCount()

◆ setRenderEffectOnly()

◆ isRenderEffectOnlyEnabled()

◆ isLayeredOnTop()

◆ supportsBlitBlendMode()

◆ beginEffectOverride()

◆ endEffectOverride()

◆ blitEffectOverride()

◆ restoreResourcesOverride()

◆ onRenderEffectOnlyChanged()

◆ clearRenderTarget() [1/2]

◆ clearRenderTarget() [2/2]

◆ addEffectPass()

◆ getLastEffectPassIndex()

◆ getEffectPass()

◆ removeAllEffectPasses()

◆ finalizeEffectPasses()

◆ beginInitialEffectPass()

◆ endInitialEffectPass()

◆ blitIntermediateEffectPass()

◆ blitFinalEffectPass()

◆ blitEffectPass()

◆ getEffectInputTexelSize()

◆ releaseEffectPassInputRenderTargets()

◆ isInitialPassRenderTargetTemporary()

◆ configureInitialEffectPass()

◆ setLayeredOnTop()

Member Data Documentation

◆ InitialEffectPassIndex